TeX 1995 July/TeX CD-ROM July 1995 (Disc 1)(Walnut Creek)(1995).ISO/biblio/bibtex/ms-dos/kempson/8bit-beta/00readme.txt

Text File | 1995-01-22 | 18KB | 452 lines

******************************************************************************
******************************************************************************
**
**  ARCHIVE HEADER INFORMATION
**
**  @Text-file{
**      filename    = "00readme.txt",
**      version     = "0.01",
**      date        = "09 November 1993",
**      time        = "21:13:31 GMT",
**
**      author      = "Niel Kempson",
**      address     = "25 Whitethorn Drive, Cheltenham, GL52 5LL, England",
**      telephone   = "[phone]",
**      FAX         = "[phone]",
**      email       = "[e-mail] (Internet)",
**
**      supported   = "yes",
**      archived    = "at all good CTAN sites, including:
**                         ftp.tex.ac.uk
**                         ftp.uni-stuttgart.de
**                         shsu.edu
**
**      abstract    = "A 32-bit implementation of BibTeX v0.99c for MS-DOS,
**                     and 32 bit OS/2.  This C language implementation is
**                     based on the original WEB source but it has been
**                     enhanced to support 8-bit input characters and it
**                     has a very large processing capacity.
**
**                     For documentation describing how to use and build
**                     this program, see the 00README.TXT file that
**                     accompanies this distribution.",
**
**      keywords    = "BibTeX, 8-bit, MS-DOS, OS/2",
**
**      codetable   = "ISO/ASCII",
**      checksum    = "",
**
**      docstring   = "This module describes the files distributed as part of
**                     the 8-bit BibTeX collection.
**
**                     The checksum field above contains a CRC-16
**                     checksum as the first value, followed by the
**                     equivalent of the standard UNIX wc (word
**                     count) utility output of lines, words, and
**                     characters.  This is produced by Robert
**                     Solovay's checksum utility."
**  }
**
**  ACKNOWLEDGEMENT
**
**      The original BIBTEX was written and copyrighted by Oren Patashnik
**      using Donald Knuth's WEB system.  This format produces a PASCAL
**      program for execution and a TeX documented version of the source
**      code. This program is a hand translation of the WEB source into C.
**
**      The changes to support 8 bit .BIB files were originally written
**      by Nicolas Brouard <[e-mail]> at the Institut
**      National d'Etudes D\'emographiques, PARIS.
**
**  COPYRIGHT
**
**      This implementation copyright (c) 1991-1993 by Niel Kempson.
**
**      This program is free software; you can redistribute it and/or
**      modify it under the terms of the GNU General Public License as
**      published by the Free Software Foundation; either version 1, or
**      (at your option) any later version.
**
**      This program is distributed in the hope that it will be useful,
**      but WITHOUT ANY WARRANTY; without even the implied warranty of
**      MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
**      General Public License for more details.
**
**      You should have received a copy of the GNU General Public License
**      along with this program; if not, write to the Free Software
**      Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
**
**      In other words, you are welcome to use, share and improve this
**      program.  You are forbidden to forbid anyone else to use, share
**      and improve what you give them.  Help stamp out software-hoarding!
**
**  CHANGE LOG
**
**      0.00 [31-Oct-1993] Niel Kempson <[e-mail]>
**          Initial 8-bit release.
**      0.01 [09-Nov-1993] Niel Kempson <[e-mail]>
**          Updated and more information added for BibTeX 3.01.
******************************************************************************
******************************************************************************

CONTENTS
********

    1.  INTRODUCTION
      1.1  Input Translation or Codepage File
      1.2  Sort Definition File
    2.  DISTRIBUTION FILES
      2.1  bt301dos.zip
      2.2  bt301os2.zip
      2.3  bt301src.zip
    3.  WHAT FILES DO I NEED ?
    4.  HOW TO GET 8-bit BibTeX
      4.1  Internet FTP
    5.  RUNNING BIBTEX
    6.  REPORTING BUGS AND REQUESTING IMPROVEMENTS
      6.1  Contacting the author
      6.2  Possible Improvements
    7.  BibTeX USE AND COPYING CONDITIONS



1.  INTRODUCTION
****************

8-bit BibTeX is an extension to the "standard" BibTeX to help it support
non-English languages using 8-bit "ASCII" character sets.  The language
support falls into two categories:

    a.  translation of 8-bit characters in the input files to equivalent
        7-bit TeX control sequences.  For example, on an IBM PC using the
        multinational code page 850, the code ^^81 represents the character
        "u" with an umlaut accent.  When BibTeX reads an ^^81 character in an
        input (i.e. .aux, .bib, .bst) file, it can be told to substitute that
        character by the TeX control sequence `\"u'.  See the "input
        translation file" section for more details.

    b.  definition of the sort order for the language.  For example, in
        German, the control sequence \"o (o umlaut) should be sorted as if it
        were the letter "o", but after ordinary "o", leading to this order:

            Trofer, Tr\"ofer, Trufer

        However, in Swedish, \"o (o umlaut) is treated as the 29th letter of
        the alphabet and these entries would be sorted as:

            Trofer, Trufer, Tr\"ofer

        BibTeX clearly needs a way of specifying the sorting order for a
        particular language.  See the "sort file" section for more details.


1.1  Input Translation or Codepage File
========================================

Codepage files contain two types of lines: comment lines and translation
lines.

Comment Lines
-------------

    Comment lines begin with percent sign and are ignored.  Blank lines are
    ignored.  Any line not beginning with "^^" is also ignored.

Translation Lines
-----------------

    Translation lines specify how 8-bit ASCII characters should be converted
    into 7-bit TeX control sequences.  These lines must be in the format:

        ^^hex-code -> TeX-code   % comment text

    where:

        hex-code  - in the range 80-FF.  Codes not specified will be
                    translated to "<?>".

        TeX-code  - any valid TeX input string using only 7-bit characters.

    For example, if the ASCII character ^^81 represents the character "u"
    with an umlaut accent, an appropriate translation line would be:

        ^^81 -> \"u     % u umlaut


By default the name of the file is "bibtex.cp" but this may be overridden by
setting the environment variable "BIBTEX_CPFILE".  If the file cannot be
opened in the current working directory, BibTeX will try the BibTeX style
file directory referred to by TEXINPUTS.  Either of these examples would be
valid on my system:

    SET BIBTEX_CPFILE=codepage.850
    SET BIBTEX_CPFILE=e:\usr\c\bibtex\test\codepage.850


1.2  Sort Definition File
=========================

NOTE: the definition of sort order hasn't yet been implemented :-(

QUESTIONS:

    a.  should the translation and sort order definitions be contained in
        separate files or in a combined code page / sort order definition
        file ?

        At first sight, it seems that the input translation rules reflect the
        computer code page used, whereas the sort order is determined by the
        language of the user.  Many European countries could use code page
        850 (multinational), but the sort order may vary in important ways.

    b.  currently BibTeX sorts characters with little intelligence because it
        simply compares the "raw" characters in the strings.  Taking the
        example of "Comsa" & "\v{C}ade\v{z}", "C" comes before "\" in the
        ASCII table so Comsa is sorted first!!

        I think the answer is to modify the search algorithm so that it
        ignores any characters apart from "0-9A-za-z".  Using the previous
        example, "Comsa" will be compared with "Cadez" and will be sorted
        after it.



2.  DISTRIBUTION FILES
**********************

8-bit BibTeX is distributed as a set of ZIP files created by the freely
available implementation of ZIP by the Info-ZIP project.  The files have all
been compressed using the new "deflation" algorithm and can only be
compressed using the Info-ZIP implementation of UNZIP, or PKUNZIP v2.04 or
later.  PKUNZIP v1.10 will not be able to unZIP the files and will complain
with a message like: "PKUNZIP: Warning! I don't know how to handle:
xxxxxxxx.xxx".

There are three ZIP files in the complete 8-bit BibTeX distribution:

    bt301dos.zip    bt301os2.zip    bt301src.zip

Their purpose and contents are summarised below.


2.1  bt301dos.zip
=================

The binary + documentation kit for MS-DOS users:

    00readme.txt        this file
    doc/COPYING         GNU copyright notice
    doc/cp850.cp        example translation file for codepage 850
    msdos/bibtex.exe    the 8-bit BibTeX program
    test/test.tex       test LaTeX source
    test/test.bib       test .bib file containing 8 bit ASCII characters


2.2  bt301os2.zip
=================

The binary + documentation kit for OS/2 users:

    00readme.txt        this file
    doc/COPYING         GNU copyright notice
    doc/cp850.cp        example translation file for codepage 850
    os2/bibtex.exe      8-bit BibTeX program for 32 bit OS/2
    test/test.tex       test LaTeX source
    test/test.bib       test .bib file containing 8 bit ASCII characters


2.3  bt301src.zip
=================

Complete source code kit to build 8-bit BibTeX on all supported systems.

    00readme.txt        this file
    doc/COPYING         GNU copyright notice
    doc/cp850.cp        example translation file for codepage 850
    test/test.tex       test LaTeX source
    test/test.bib       test .bib file containing 8 bit ASCII characters

    bibtex.h            definition of global parameters and limits
    datatype.h          definition of custom data types
    gblprocs.h          forward declaration of all global functions
    gblvars.h           declaration of global variables
    sysdep.h            determine the compiler and environment

    bibtex.c            main source including system dependent code
    bibtex-1.c          part 1 of the system independent functions
    bibtex-2.c          part 2 of the system independent functions
    bibtex-3.c          part 3 of the system independent functions
    bibtex-4.c          part 4 of the system independent functions

    os2.mak             makefile for various OS/2 compilers
    os2msdos.mak        OS/2 makefile to build DOS executables



3.  WHAT FILES DO I NEED ?
**************************

Although there are three ZIP files in the master distribution, it's most
unlikely that you will want them all.  The most likely requirements are
summarised below, along with the files that I recommended you to fetch.

    Q.  I want to be able to use 8-bit BibTeX.  I'm not interested in
        building from sources, I just want a program.  What do I need ?

    A.  "Load and go" kits containing executables and help files are
        available for:

            MS-DOS      bt301dos.zip
            OS/2        bt301os2.zip


    Q.  I want to build 8-bit BibTeX from source code.  What do I need ?

    A.  You need "bt301src.zip".


    Q.  I want to port 8-bit BibTeX to another environment.  What do I need ?

    A.  Firstly, a vote of thanks.  You'll need everything for building
        from source code.  Please also contact the author so that he can
        provide as much help as possible.  The source code doesn't contain
        any system-specific items and should very easily port to Unix or
        VAX/VMS.



4.  HOW TO GET 8-bit BibTeX
***************************

8-bit BibTeX is available via Internet FTP:


    Host:               ftp.tex.ac.uk
    Directory:          tex-archive/biblio/bibtex/kempson/8bit-beta
    File to get first:  00readme.txt (this file)



5.  RUNNING BIBTEX
******************

In case you're used to emTeX, 8-bit BibTeX currently uses these environment
variables when opening files:

    .aux files -  BibTeX attempts to open the file in the current working
                  directory.  If the open fails, an error is reported.

    .bib files -  BibTeX attempts to open the file in the current working
                  directory.  If the open fails, the translation of the DOS
                  environment variable TEXBIB is prepended to the file name.
                  If this open fails, an error is reported.

    .bst files -  BibTeX attempts to open the file in the current working
                  directory.  If the open fails, the translation of the DOS
                  environment variable TEXINPUTS is prepended to the file
                  name.  If this open fails, an error is reported.

    .cp files  -  BibTeX attempts to open the file in the current working
                  directory.  If the open fails, the translation of the DOS
                  environment variable TEXINPUTS is prepended to the file
                  name.  If this open fails, an error is reported.

The translations of these environment variables must be suitable for
prepending to a file name and extension.   If the translated string does not
end in a '\' or ':', a '\' is added.  Some valid examples of SETting these
variables are:

    SET TEXINPUTS=c:\tex\inputs\
    SET TEXINPUTS=c:\tex\inputs
    SET TEXINPUTS=f:

Because the environment variable must be suitable for prepending, search
paths are not permitted.  Examples of invalid SETs are:

    SET TEXINPUTS=c:\tex\inputs;d:\latex
    SET TEXINPUTS=c:\tex\inputs\;f:\tmp



6.  REPORTING BUGS AND REQUESTING IMPROVEMENTS
**********************************************


6.1  Contacting the author
==========================

The author will try to fix bugs where possible and will consider requests for
improvements.  If you are reporting a bug, please provide as much information
as possible (e.g. operating environment,  8-bit BibTeX version and source,
exact error message and the offending files if possible).  The most common
message is of the form "BibTeX doesn't work on XXXX"; such a message will
result in a request for you to provide as much information as possible.

The implementor of this 8-bit BibTeX is:

    Niel Kempson
    25 Whitethorn Drive, Cheltenham, GL52 5LL, England
    E-mail: [e-mail] (Internet)


6.2  Possible Improvements
==========================

These changes would make this port of BibTeX a lot better:

    o   support command line options to specify code page file, memory
        capacity options etc;

    o   use the same environment variables as emTeX;

    o   support 8 bit output;

    o   implement a customisable sorting order.

The first three are relatively easy, but the fourth is really quite
awkward.  At the moment, all characters are sorted using simple ASCII
values for comparison, not the "proper" order of the national alphabet.

I haven't used BibTeX seriously for several years and I've forgotten most of
the lessons I learned while porting it, so I'm not likely to be making these
improvements myself.  However, if you feel up to the challenge, please feel
welcome to use my source code as a starting point.  You'll have to conform to
the original use and copying conditions below, just as I do.


7.  BibTeX USE AND COPYING CONDITIONS
*************************************

The programs currently being distributed that relate to 8-bit BibTeX are
*free*;  this means that everyone may use them and redistribute them freely.
The 8-bit BibTeX-related programs are not in the public domain;  they are
copyrighted and there are restrictions on their distribution, but these
restrictions are designed to permit everything that a good cooperating
citizen would want to do.  What is not allowed is to try to prevent others
from further sharing any version of these programs that they might get from
you.

Specifically, we want to make sure that you have the right to give away
copies of the programs that relate to 8-bit BibTeX, that you receive source
code or else can get it if you want it, that you can change these programs or
use pieces of them in new free programs, and that you know you can do these
things.

To make sure that everyone has such rights, we have to forbid you to deprive
anyone else of these rights.  For example, if you distribute copies of the
8-bit BibTex related programs, you must give the recipients all the rights
that you have.  You must make sure that they, too, receive or can get the
source code.  And you must tell them their rights.

Also, for our own protection, we must make certain that everyone finds out
that there is no warranty for the programs that relate to 8-bit BibTeX.  If
these programs are modified by someone else and passed on, we want their
recipients to know that what they have is not what we distributed, so that
any problems introduced by others will not reflect on our reputation.

The precise conditions of the licences for the programs currently being
distributed that relate to 8-bit BibTeX are found in the General Public
Licences that accompany them.

******************************** END OF FILE *******************************